brainGraph (version 3.1.0)

Atlas Helpers: Atlas helper functions

Description

guess_atlas tries to determine which atlas is being used based on the data; i.e., the number of vertices/regions.

as_atlas and create_atlas converts/coerces an object to a a data.table, or creates one, that is compatible with brainGraph.

Usage

guess_atlas(x)
as_atlas(object)
create_atlas(regions, coords, lobes, hemis, other = NULL)

Value

guess_atlas - Character string; either the matched atlas or

NA

as_atlas and create_atlas return a data.table

that conforms to other atlases in the package, or exits with an error.

Arguments

x, object

An object to test or convert to an atlas data.table

regions

Character vector of region names

coords

Numeric matrix of spatial coordinates; must have 3 columns

lobes

Character or factor vector of lobe membership

hemis

Character or factor vector of hemisphere membership. There should probably not be more than 3 unique elements (for left, right, and bi-hemispheric regions)

other

A named list of vectors with other data. The names of the list will become column names in the return object.

Guessing the atlas from an object

There are several valid inputs to guess_atlas:

data.table

The atlas will be guessed based on the number of columns (subtracting by 1 if a “Study ID” column is present). This is the same behavior as for data.frame objects, as well.

igraph

The vertex count

brainGraph

If there is a atlas graph-level attribute, it will return that. Otherwise, the vertex count.

matrix,array

The number of rows, which should equal the number of columns if the input is a connectivity matrix.

Note that this will only work properly for atlases that are currently in the package. If you are using a custom atlas and you receive errors, please open an issue on GitHub.

Coercing to an atlas

There are several things as_atlas tries to do to make it work without error:

• Coerce the object to data.table

• Add a column of integers named index

• Change columns named 'x', 'y', or 'z' to have .mni at the end

• Convert the lobe and hemi columns to be factors

Examples

my_atlas <- data.frame(name=paste('Region', 1:10), x.mni=rnorm(10),
  y.mni=rnorm(10), z.mni=rnorm(10),
  lobe=rep(c('Frontal', 'Parietal', 'Temporal', 'Occipital', 'Limbic'), 2),
  hemi=c(rep('L', 5), rep('R', 5)))
my_atlas2 <- as_atlas(my_atlas)
str(my_atlas)
str(my_atlas2)
regions <- paste('Region', 1:10)
xyz <- matrix(rnorm(30), nrow=10, ncol=3)
lobe <- rep(c('Frontal', 'Parietal', 'Temporal', 'Occipital', 'Limbic'), 2)
hemi <- c(rep('L', 5), rep('R', 5))
other <- list(network=rep(c('Default mode', 'Task positive'), 5))
my_atlas <- create_atlas(regions, xyz, lobe, hemi, other)
str(my_atlas)